From 1268c17983165cee4d94c53dc71ae7889bedc15f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20Jard=C3=B3n?= Date: Mon, 15 Nov 2010 04:58:21 +0100 Subject: [PATCH] docs: Move documentation to inline comments: general --- docs/reference/gdk/tmpl/.gitignore | 1 + docs/reference/gdk/tmpl/general.sgml | 366 --------------------------- gdk/gdk.c | 68 +++-- gdk/gdkmain.h | 37 +++ gdk/gdktypes.h | 15 +- gdk/gdkwindow.c | 17 +- 6 files changed, 108 insertions(+), 396 deletions(-) delete mode 100644 docs/reference/gdk/tmpl/general.sgml diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore index ef29778065..5b8a121d69 100644 --- a/docs/reference/gdk/tmpl/.gitignore +++ b/docs/reference/gdk/tmpl/.gitignore @@ -6,6 +6,7 @@ gdkdisplay.sgml gdkdisplaymanager.sgml gdkscreen.sgml gdktesting.sgml +general.sgml keys.sgml pixbufs.sgml regions.sgml diff --git a/docs/reference/gdk/tmpl/general.sgml b/docs/reference/gdk/tmpl/general.sgml deleted file mode 100644 index 089b44d677..0000000000 --- a/docs/reference/gdk/tmpl/general.sgml +++ /dev/null @@ -1,366 +0,0 @@ - -General - - -Library initialization and miscellaneous functions - - - -This section describes the GDK initialization functions and miscellaneous -utility functions. - - - - - - - - - - - - - - - -Initializes the GDK library and connects to the X server. -If initialization fails, a warning message is output and the application -terminates with a call to exit(1). - - -Any arguments used by GDK are removed from the array and @argc and @argv are -updated accordingly. - - -GTK+ initializes GDK in gtk_init() and so this function is not usually needed -by GTK+ applications. - - -@argc: the number of command line arguments. -@argv: the array of command line arguments. - - - - -Initializes the GDK library and connects to the X server, returning %TRUE on -success. - - -Any arguments used by GDK are removed from the array and @argc and @argv are -updated accordingly. - - -GTK+ initializes GDK in gtk_init() and so this function is not usually needed -by GTK+ applications. - - -@argc: the number of command line arguments. -@argv: the array of command line arguments. -@Returns: %TRUE if initialization succeeded. - - - - - - - -@argc: -@argv: - - - - - - - -@void: -@Returns: - - - - -Initializes the support for internationalization by calling the setlocale() -system call. This function is called by gtk_set_locale() and so GTK+ -applications should use that instead. - - -The locale to use is determined by the LANG environment variable, -so to run an application in a certain locale you can do something like this: - - - export LANG="fr" - ... run application ... - - - - -If the locale is not supported by X then it is reset to the standard "C" -locale. - - -@void: -@Returns: the resulting locale. - - - - - - -@sm_client_id: - - - - - - - -@void: - - - - - - - -@startup_id: - - - - -Gets the program class. Unless the program class has explicitly -been set with gdk_set_program_class() or with the -commandline option, the default value is the program name (determined -with g_get_prgname()) with the first character converted to uppercase. - - -@void: -@Returns: the program class. - - - - -Sets the program class. The X11 backend uses the program class to set -the class name part of the WM_CLASS property on -toplevel windows; see the ICCCM. - - -@program_class: a string. - - - - -Gets the name of the display, which usually comes from the DISPLAY -environment variable or the command line option. - - -@void: -@Returns: the name of the display. - - - - -Flushes the X output buffer and waits until all requests have been processed -by the server. This is rarely needed by applications. It's main use is for -trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop(). - - -@void: - - - - - - -@void: -@Returns: - - - - - - -@void: -@Returns: - - - - - - -@void: -@Returns: - - - - - - -@void: -@Returns: - - - - -Grabs the pointer (usually a mouse) so that all events are passed to this -application until the pointer is ungrabbed with gdk_pointer_ungrab(), or -the grab window becomes unviewable. -This overrides any previous pointer grab by this client. - - -Pointer grabs are used for operations which need complete control over mouse -events, even if the mouse leaves the application. -For example in GTK+ it is used for Drag and Drop, for dragging the handle in -the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList -widgets. - - -Note that if the event mask of an X window has selected both button press and -button release events, then a button press event will cause an automatic -pointer grab until the button is released. -X does this automatically since most applications expect to receive button -press and release events in pairs. -It is equivalent to a pointer grab on the window with @owner_events set to -%TRUE. - - -If you set up anything at the time you take the grab that needs to be cleaned -up when the grab ends, you should handle the #GdkEventGrabBroken events that -are emitted when the grab ends unvoluntarily. - - -@window: the #GdkWindow which will own the grab (the grab window). -@owner_events: if %FALSE then all pointer events are reported with respect to -@window and are only reported if selected by @event_mask. If %TRUE then pointer -events for this application are reported as normal, but pointer events outside -this application are reported with respect to @window and only if selected by -@event_mask. In either mode, unreported events are discarded. -@event_mask: specifies the event mask, which is used in accordance with -@owner_events. Note that only pointer events (i.e. button and motion events) - may be selected. -@confine_to: If non-%NULL, the pointer will be confined to this -window during the grab. If the pointer is outside @confine_to, it will -automatically be moved to the closest edge of @confine_to and enter -and leave events will be generated as necessary. -@cursor: the cursor to display while the grab is active. If this is %NULL then -the normal cursors are used for @window and its descendants, and the cursor -for @window is used for all other windows. -@time_: the timestamp of the event which led to this pointer grab. This usually -comes from a #GdkEventButton struct, though %GDK_CURRENT_TIME can be used if -the time isn't known. -@Returns: %GDK_GRAB_SUCCESS if the grab was successful. - - - - -Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate -success or the reason for the failure of the grab attempt. - - -@GDK_GRAB_SUCCESS: the resource was successfully grabbed. -@GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client. -@GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the - specified time. -@GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not - viewable. -@GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client. - - - - - - -@time_: - - - - - - - - -@void: -@Returns: - - - - - - - -@msec: - - - - -Grabs the keyboard so that all events are passed to this -application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). -This overrides any previous keyboard grab by this client. - - -If you set up anything at the time you take the grab that needs to be cleaned -up when the grab ends, you should handle the #GdkEventGrabBroken events that -are emitted when the grab ends unvoluntarily. - - -@window: the #GdkWindow which will own the grab (the grab window). -@owner_events: if %FALSE then all keyboard events are reported with respect to -@window. If %TRUE then keyboard events for this application are reported as -normal, but keyboard events outside this application are reported with respect -to @window. Both key press and key release events are always reported, -independant of the event mask set by the application. -@time_: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is -available. -@Returns: %GDK_GRAB_SUCCESS if the grab was successful. - - - - - - -@time_: - - - - - - -@void: - - - - - - - -@void: - - - - - - - - - - - - - - -@void: - - - - -This macro is defined if GDK is configured to use the X11 backend. - - - - - - -This macro is defined if GDK is configured to use the win32 backend. - - - - diff --git a/gdk/gdk.c b/gdk/gdk.c index ba6582db66..8c701ff6e6 100644 --- a/gdk/gdk.c +++ b/gdk/gdk.c @@ -38,6 +38,17 @@ #include #include + +/** + * SECTION:general + * @Short_description: Library initialization and miscellaneous functions + * @Title: General + * + * This section describes the GDK initialization functions and miscellaneous + * utility functions. + */ + + typedef struct _GdkPredicate GdkPredicate; struct _GdkPredicate @@ -338,25 +349,19 @@ gdk_display_open_default_libgtk_only (void) /** * gdk_init_check: - * @argc: (inout): - * @argv: (array length=argc) (inout): + * @argc: (inout): the number of command line arguments. + * @argv: (array length=argc) (inout): the array of command line arguments. * - * Initialize the library for use. + * Initializes the GDK library and connects to the X server, returning %TRUE on + * success. * - * Arguments: - * "argc" is the number of arguments. - * "argv" is an array of strings. - * - * Results: - * "argc" and "argv" are modified to reflect any arguments - * which were not handled. (Such arguments should either - * be handled by the application or dismissed). If initialization - * fails, returns FALSE, otherwise TRUE. + * Any arguments used by GDK are removed from the array and @argc and @argv are + * updated accordingly. * - * Side effects: - * The library is initialized. + * GTK+ initializes GDK in gtk_init() and so this function is not usually needed + * by GTK+ applications. * - *-------------------------------------------------------------- + * Returns: %TRUE if initialization succeeded. */ gboolean gdk_init_check (int *argc, @@ -370,8 +375,18 @@ gdk_init_check (int *argc, /** * gdk_init: - * @argc: (inout): - * @argv: (array length=argc) (inout): + * @argc: (inout): the number of command line arguments. + * @argv: (array length=argc) (inout): the array of command line arguments. + * + * Initializes the GDK library and connects to the X server. + * If initialization fails, a warning message is output and the application + * terminates with a call to exit(1). + * + * Any arguments used by GDK are removed from the array and @argc and @argv are + * updated accordingly. + * + * GTK+ initializes GDK in gtk_init() and so this function is not usually needed + * by GTK+ applications. */ void gdk_init (int *argc, char ***argv) @@ -772,13 +787,30 @@ gdk_threads_add_timeout_seconds (guint interval, interval, function, data, NULL); } - +/** + * gdk_get_program_class: + * + * Gets the program class. Unless the program class has explicitly + * been set with gdk_set_program_class() or with the + * commandline option, the default value is the program name (determined + * with g_get_prgname()) with the first character converted to uppercase. + * + * Returns: the program class. + */ G_CONST_RETURN char * gdk_get_program_class (void) { return gdk_progclass; } +/** + * gdk_set_program_class: + * @program_class: a string. + * + * Sets the program class. The X11 backend uses the program class to set + * the class name part of the WM_CLASS property on + * toplevel windows; see the ICCCM. + */ void gdk_set_program_class (const char *program_class) { diff --git a/gdk/gdkmain.h b/gdk/gdkmain.h index f2ceaaa4bf..75ffb4e62a 100644 --- a/gdk/gdkmain.h +++ b/gdk/gdkmain.h @@ -50,6 +50,27 @@ gboolean gdk_init_check (gint *argc, void gdk_add_option_entries_libgtk_only (GOptionGroup *group); void gdk_pre_parse_libgtk_only (void); +/** + * gdk_set_locale: + * + * Initializes the support for internationalization by calling the setlocale() + * system call. This function is called by gtk_set_locale() and so GTK+ + * applications should use that instead. + * + * The locale to use is determined by the LANG environment variable, + * so to run an application in a certain locale you can do something like this: + * + * + * export LANG="fr" + * ... run application ... + * + * + * + * If the locale is not supported by X then it is reset to the standard "C" + * locale. + * + * Returns: the resulting locale. + */ gchar* gdk_set_locale (void); void gdk_enable_multidevice (void); @@ -68,6 +89,15 @@ void gdk_error_trap_pop_ignored (void); G_CONST_RETURN gchar *gdk_get_display_arg_name (void); + +/** + * gdk_get_display: + * + * Gets the name of the display, which usually comes from the DISPLAY + * environment variable or the command line option. + * + * Returns: the name of the display. + */ gchar* gdk_get_display (void); #ifndef GDK_MULTIDEVICE_SAFE @@ -102,6 +132,13 @@ void gdk_beep (void); #endif /* GDK_MULTIHEAD_SAFE */ +/** + * gdk_flush: + * + * Flushes the X output buffer and waits until all requests have been processed + * by the server. This is rarely needed by applications. It's main use is for + * trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop(). + */ void gdk_flush (void); G_END_DECLS diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index 53937d8ca6..44efa3fa9c 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -196,9 +196,18 @@ typedef enum GDK_ERROR_MEM = -4 } GdkStatus; -/* We define specific numeric values for these constants, - * since old application code may depend on them matching the X values - * We don't actually depend on the matchup ourselves. +/** + * GdkGrabStatus: + * @GDK_GRAB_SUCCESS: the resource was successfully grabbed. + * @GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client. + * @GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the + * specified time. + * @GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not + * viewable. + * @GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client. + * + * Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate + * success or the reason for the failure of the grab attempt. */ typedef enum { diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index d186b4dce5..c2485980f5 100644 --- a/gdk/gdkwindow.c +++ b/gdk/gdkwindow.c @@ -8864,8 +8864,7 @@ _gdk_display_set_window_under_pointer (GdkDisplay *display, * Pointer grabs are used for operations which need complete control over mouse * events, even if the mouse leaves the application. * For example in GTK+ it is used for Drag and Drop, for dragging the handle in - * the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList - * widgets. + * the #GtkHPaned and #GtkVPaned widgets. * * Note that if the event mask of an X window has selected both button press and * button release events, then a button press event will cause an automatic @@ -8982,13 +8981,13 @@ gdk_pointer_grab (GdkWindow * window, * gdk_keyboard_grab: * @window: the #GdkWindow which will own the grab (the grab window). * @owner_events: if %FALSE then all keyboard events are reported with respect to - * @window. If %TRUE then keyboard events for this application are - * reported as normal, but keyboard events outside this application - * are reported with respect to @window. Both key press and key - * release events are always reported, independant of the event mask - * set by the application. - * @time: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is -available. + * @window. If %TRUE then keyboard events for this application are + * reported as normal, but keyboard events outside this application + * are reported with respect to @window. Both key press and key + * release events are always reported, independant of the event mask + * set by the application. + * @time_: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is + * available. * * Grabs the keyboard so that all events are passed to this * application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). -- 2.30.2